<html>
<head>
<title>ECW -- Enhanced Compressed Wavelets (.ecw)</title>
</head>

<body bgcolor="#ffffff">

<h1>ECW -- Enhanced Compressed Wavelets (.ecw)</h1>

GDAL supports reading and writing ECW files using the ERDAS ECW/JP2 SDK developed by
Hexagon Geospatial (formerly Intergraph, ERDAS, ERMapper). Support is optional and
requires linking in the libraries available from the ECW/JP2 SDK Download page.<p>

<h3>Licensing</h3>

The ERDAS ECW/JP2 SDK v5.x is available under multiple license types. For Desktop usage, decoding
any sized ECW/JP2 image is made available free of charge. To compress, deploy on a Server platform, or decode
unlimited sized files on Mobile platforms a license must be purchased from Hexagon Geospatial.<p>


<h3>History</h3>
<ul>
<li>v3.x - Last release, 2006</li>
<li>v4.x - Last release, 2012</li>
<li>v5.x - Active development, 2013 - current</li>
</ul>

<h2>Creation Options</h2>

The ERDAS ECW/JP2 v4.x and v5.x SDK is only free for image decompression.  To
compress images it is necessary to build with the read/write SDK and to
provide an OEM licensing key at runtime which may be purchased from ERDAS.<p>

For those still using the ECW 3.3 SDK, images less than 500MB may be
compressed for free, while larger images require licensing from ERDAS.  See
the licensing agreement and the LARGE_OK option.<p>

Files to be compressed into ECW format must also
be at least 128x128.  ECW currently only supports 8 bits per channel for
ECW Version 2 files. ECW Version 3 files supports 16 bits per channel
(as Uint16 data type). Please see Creation options to enable ECW V3 files writing <p>

When writing coordinate system information to ECW files, many less
common coordinate systems are not mapped properly.  If you know the
ECW name for the coordinate system you can force it to be set at
creation time with the PROJ and DATUM creation options. <p>

ECW format does not support creation of overviews since the ECW format
is already considered to be optimized for "arbitrary overviews". <P>

<h2>Creation Options:</h2>

<ul>

<li> <b>LARGE_OK=YES</b>: <i>(v3.x SDK only)</i> Allow compressing files larger than 500MB in accordance with EULA terms. Deprecated since v4.x and
replaced by ECW_ENCODE_KEY & ECW_ENCODE_COMPANY.<p>

<li> <b>ECW_ENCODE_KEY=key</b>: <i>(v4.x SDK or higher)</i> Provide the OEM encoding key to unlock encoding capability
up to the licensed gigapixel limit.  The key is approximately 129 hex digits long. The Company and Key must match and must be re-generated with each minor release of the SDK.  It may also be provided globally as a configuration option.<p>

<li> <b>ECW_ENCODE_COMPANY=name</b>: <i>(v4.x SDK or higher)</i> Provide the name of the company in the issued
OEM key (see ECW_ENCODE_KEY).  The Company and Key must match and must be re-generated with each minor release of the SDK.  It may also be provided
globally as a configuration option.<p>

<li> <b>TARGET=percent</b>: Set the target size reduction as a percentage of
the original.  If not provided defaults to 90% for greyscale images, and 95%
for RGB images.<p>

<li> <b>PROJ=name</b>: Name of the ECW projection string to use.
Common examples are NUTM11, or GEODETIC.<p>

<li> <b>DATUM=name</b>: Name of the ECW datum string to use.
Common examples are WGS84 or NAD83.<p>

<li> <b>UNITS=name</b>: (GDAL &gt;= 1.9.0) Name of the ECW projection units to use :
METERS (default) or FEET (us-foot).<p>

<li> <b>ECW_FORMAT_VERSION=2/3</b>: (GDAL &gt;= 1.10.0) When build with the ECW 5.x SDK this option can be set to
allow ECW Version 3 files to be created. Default, 2 to retain widest compatibility.<p>

</ul>

<h2> Configuration Options </h2>

The ERDAS ECW SDK supports a variety of
<a href="http://trac.osgeo.org/gdal/wiki/ConfigOptions">runtime configuration
options</a> to control various features.  Most of these are exposed as GDAL
configuration options.  See the ECW SDK documentation for full details on the
meaning of these options.

<ul>
<li> <b>ECW_CACHE_MAXMEM=bytes</b>: maximum bytes of RAM used for in-memory
caching.  If not set, up to one quarter of physical RAM will be used by the
SDK for in-memory caching.<p>

<li> <b>ECWP_CACHE_LOCATION=path</b>: Path to a directory to use for caching
ECWP results.  If unset ECWP caching will not be enabled.<p>

<li> <b>ECWP_CACHE_SIZE_MB=number_of_megabytes</b>: The maximum
number of megabytes of space in the ECWP_CACHE_LOCATION to be used for
caching ECWP results.<p>

<li> <b>ECWP_BLOCKING_TIME_MS</b>: time an ecwp:// blocking read will wait
before returning - default 10000 ms.<p>

<li> <b>ECWP_REFRESH_TIME_MS</b>: time delay between blocks arriving and the
next refresh callback - default 10000 ms.  For the purposes of GDAL this is
the amount of time the driver will wait for more data on an ecwp connection
for which the final result has not yet been returned.  If set small then
RasterIO() requests will often produce low resolution results.<p>

<li> <b>ECW_TEXTURE_DITHER=TRUE/FALSE</b>: This may be set to FALSE to disable
dithering when decompressing ECW files.  Defaults to TRUE.<p>

<li> <b>ECW_FORCE_FILE_REOPEN=TRUE/FALSE</b>: This may be set to TRUE to
force open a file handle for each file for each connection made.  Defaults to
FALSE.<p>

<li> <b>ECW_CACHE_MAXOPEN=number</b>: The maximum number of files to keep
open for ECW file handle caching.  Defaults to unlimited.<p>

<li> <b>ECW_RESILIENT_DECODING=TRUE/FALSE</b>: Controls whether the reader
should be forgiving of errors in a file, trying to return as much data as is
available.  Defaults to TRUE.  If set to FALSE an invalid file will result
in an error.<p>

</ul>

<h3>ECW Version 3 Files</h3>
(Starting with GDAL 1.10.0)<p>

ECW 5.x SDK introduces a new file format version which,
<ol>
<li>Storage of data statistics, histograms, metadata, RPC information within the file header</li>
<li>Support for UInt16 data type</li>
<li>Ability to update regions within an existing ECW v3 file</li>
<li>Introduces other space saving optimizations</li>
</ol>

Note: This version is not backward compatible and will fail to decode in v3.x or v4.x ECW/JP2 SDK's. The File VERSION Metadata will advertise whether the file is ECW v2 or ECW v3.

<h3>ECWP</h3>
In addition to local files, this driver also supports access to streaming network
imagery services using the proprietary "ECWP" protocol from the ERDAS APOLLO product.  Use the full ecwp:// prefixed dataset url
as input.  When built with ECW/JP2 SDK v4.1 or newer it
is also possible to take advantage of
<a href="http://trac.osgeo.org/gdal/wiki/rfc24_progressive_data_support">
RFC 24</a> for asynchronous / progressive streaming access to ECWP services.<p>

<h3>Metadata / Georeferencing</h3>

(Starting with GDAL 1.9.0)<p>

The PROJ, DATUM and UNITS found in the ECW header are
reported in the ECW metadata domain. They can also be set with the SetMetadataItem()
method, in order to update the header information of an existing ECW file,
opened in update mode, without modifying the imagery.<p>

The geotransform and projection can also be modified with the SetGeoTransform()
and SetProjection() methods. If the projection is set with SetProjection() and
the PROJ, DATUM or UNITS with SetMetadataItem(), the later values will override the values
built from the projection string.<p>

<h3>File Metadata Keys: </h3>

<ul>
<li>FILE_METADATA_ACQUISITION_DATE
<li>FILE_METADATA_ACQUISITION_SENSOR_NAME
<li>FILE_METADATA_ADDRESS
<li>FILE_METADATA_AUTHOR
<li>FILE_METADATA_CLASSIFICATION
<li>FILE_METADATA_COMPANY - should be set to ECW_ENCODE_COMPANY
<li>FILE_METADATA_COMPRESSION_SOFTWARE - updated during recompression
<li>FILE_METADATA_COPYRIGHT
<li>FILE_METADATA_EMAIL
<li>FILE_METADATA_TELEPHONE
<li>CLOCKWISE_ROTATION_DEG
<li>COLORSPACE
<li>COMPRESSION_DATE
<li>COMPRESSION_RATE_ACTUAL
<li>COMPRESSION_RATE_TARGET
<li>VERSION
</ul>

<h2>See Also</h2>

<ul>
<li> Implemented as <tt>gdal/frmts/ecw/ecwdataset.cpp</tt>.<p>

<li> ECW/JP2 SDK available at <a href="http://hexagongeospatial.com/products/data-management-compression/ecw/erdas-ecw-jp2-sdk">www.hexagongeospatial.com</a>
<li> Further product information available in the <a href="http://hexagongeospatial.com/products/data-management-compression/ecw/erdas-ecw-jp2-sdk/literature">User Guide</a>
<li> Support for non-GDAL specific issues should be directed to the <a href="https://sgisupport.intergraph.com/infocenter/index?page=forums&forum=507301383c17ef4e013d8dfa30c2007ef1">Hexagon Geospatial public forum</a>
<li> <a href="http://trac.osgeo.org/gdal/wiki/ECW">GDAL ECW Build Hints</a>
</ul>

</body>
</html>
